Skip to content

feat: store imported sources once and share import resolution between compileFile and compileString - #453

Merged
rkalis merged 1 commit into
nextfrom
feat/imports-debug-sources
Sep 28, 2026
Merged

rkalis merged 1 commit into
nextfrom
feat/imports-debug-sources

Conversation

@rkalis

@rkalis rkalis commented Sep 26, 2026

Copy link
Copy Markdown
Member

Closes #449, and replaces #450.

Artifacts now store the source code of every imported file once, in a format that compileString accepts directly, so any artifact can be recompiled from itself:

compileString(artifact.source, { ...artifact.compiler.options, files: artifact.debug?.sources })

Changes

  • debug.sources: every imported file's source code is stored once in the artifact, instead of the full file text on every debug frame (DebugFrame.source is removed). It contains every file the compiler reads, including files whose definitions are unused, so that recompiling works.
  • Logical paths: imported files are identified by a logical path that compileFile and compileString compute in the same (shared) way. This is the file's key in files and debug.sources, and the frame's sourceFile:
    • Local files: a POSIX path relative to the main source (unchanged).
    • Package files: package:<import path>, e.g. package:@example/math-lib/math.cash. Relative imports inside a package stay inside it. This keeps package files apart from local files with the same path, which previously resolved to the same files key (so e.g. a missing ./ in import "lib/math.cash" compiled with compileString but not with compileFile).
    • The resolvers now only locate and read files (by real path on disk, by logical path in memory), so the naming and de-duplication logic is shared.
  • Symlinks: imports are resolved from real (symlink-resolved) paths like in Node.js, so a package's own dependencies are found when it is installed with pnpm or linked with npm link or workspaces. Linked packages keep their package names in the artifact.
  • Rejected imports:
    • Importing multiple copies of a package (e.g. node_modules/foo and node_modules/bar/node_modules/foo), since one logical path can only refer to one file. These copies usually define the same functions, so this was already a redefinition error in practice.
    • Absolute import paths, which only work on one machine and would end up in debug.sources.
  • Readers: the SDK's debug frame resolution and the BitAuth IDE formatting read imported sources from debug.sources.
  • TS artifacts: object keys that are not identifiers (like the file names in debug.sources) are quoted.
  • Docs for debug.sources, recompiling from an artifact, package: keys, symlinks and absolute imports.

Only formats and behaviour from 0.14 prereleases change, so there is no compatibility for per-frame source or the old package keys.

Tests

  • Every import fixture, and pnpm, workspace link and symlinked directory layouts (created in a temp dir), are recompiled from their own debug.sources and must give an identical artifact.
  • debug.sources contains files without used definitions, and is absent without imports.
  • Package files are not resolved from local files keys, local and package files with the same path stay separate, and transitive package dependencies give the same artifact from disk and from memory.
  • Transitive dependencies under a pnpm layout resolve (fails on the old resolver), packages reached through different symlinks are imported once, and linked packages and symlinked projects keep their names.
  • Multiple copies of a package and absolute import paths are rejected.

yarn build, yarn test, yarn lint and yarn spellcheck pass.

Note: the VS Code extension mirrors cashc's import resolution in ImportGraph.ts, and will need a follow-up to use the new package: keys and real paths.

🤖 Generated with Claude Code

… compileFile and compileString

- Store the source code of every imported file once in the artifact's
  `debug.sources`, replacing the full file text on every debug frame. It is
  keyed by the file's logical path (also used as the frame's `sourceFile`), so
  it can be passed as `files` to `compileString` to recompile the artifact
- Identify imported files by a logical path that compileFile and compileString
  compute the same way: a POSIX path relative to the main source, or
  `package:<import path>` for files in packages. Package files are provided
  under `package:` keys in compileString's `files` option
- Resolve imports from real (symlink-resolved) paths, so a package's own
  dependencies are found when it is installed with pnpm or linked
- Reject importing multiple copies of a package, and absolute import paths
- Quote object keys that are not identifiers in TS artifacts

Closes #449

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vercel

vercel Bot commented Sep 26, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
cashscript Ready Ready Preview Sep 26, 2026 2:38pm UTC

Request Review

@codecov

codecov Bot commented Sep 26, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 95.52239% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.75%. Comparing base (d2e3593) to head (3ffb352).

Files with missing lines Patch % Lines
packages/utils/src/artifact.ts 0.00% 1 Missing and 2 partials ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             next     #453      +/-   ##
==========================================
- Coverage   88.76%   88.75%   -0.02%     
==========================================
  Files          61       61              
  Lines        5012     5025      +13     
  Branches      927      933       +6     
==========================================
+ Hits         4449     4460      +11     
- Misses        433      434       +1     
- Partials      130      131       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@rkalis
rkalis merged commit ff9e631 into next Sep 28, 2026
5 checks passed
@rkalis
rkalis deleted the feat/imports-debug-sources branch September 28, 2026 09:19

This branch was successfully deployed

1 active deployment
Preview — 3ffb352d Deployed Sep 26, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant